… filter Or guard + retrieve defense-in-depth

Closes task #83 per PM @不穷 dispatch (msg=29c9e753). Folds 4 P1-V
items from task #61 spec v1 § 2.3 into a single PR:

P1-V1 — collection init failure contract documentation
------------------------------------------------------
``ensure_collection`` Protocol docstring now spells out the cross-
adapter contract (idempotent / race-safe / fail-loud / cache-not-
poisoned-on-failure). Both adapters already implement these
behaviours; the documentation closes the spec drift gap so future
implementers have a checklist.

P1-V2 — batch upsert atomicity capability declaration
-----------------------------------------------------
New :class:`VectorBackendCapabilities` frozen dataclass on the base
module declares static per-backend behaviour flags. Each
``VectorStoreConnector`` subclass exposes an instance via the
``BACKEND_CAPABILITIES`` class-level attribute:

* ``PgvectorVectorStoreConnector.BACKEND_CAPABILITIES.supports_atomic_batch_upsert = True``
  (PGVector wraps bulk INSERT ON CONFLICT in ``engine.begin()`` —
  mid-batch failure rolls back the whole batch).
* ``QdrantVectorStoreConnector.BACKEND_CAPABILITIES.supports_atomic_batch_upsert = False``
  (Qdrant ``client.upsert(points, wait=True)`` is best-effort
  per-point — partial writes possible on mid-batch failure).

``upsert`` Protocol docstring now points at the capability flag so
callers know to chunk + verify on backends that declare ``False``.

P1-V3 — filter Or empty-parts guard
-----------------------------------
``Or.__post_init__`` already rejects empty ``parts`` at DSL
construction. Both adapter translators now also guard at the
translator boundary so a future refactor that bypasses the
constructor (e.g. ``object.__setattr__(or_node, "parts", ())`` on
the frozen dataclass, or a ``dataclasses.replace`` with empty
parts) can't silently degrade to a vacuous "match everything"
disjunction:

* ``aperag/vectorstore/pgvector_connector.py:_SqlFilter._walk`` —
  raises ``UnsupportedFilterError`` on empty post-walk parts.
* ``aperag/vectorstore/qdrant_connector.py:_translate_filter`` —
  raises ``UnsupportedFilterError`` on empty post-prune subs (so
  ``rest.Filter(should=[])`` — which Qdrant treats as match-all —
  is unreachable).

P1-V4 — Qdrant legacy mode defense-in-depth
-------------------------------------------
``QdrantVectorStoreConnector.retrieve`` now applies the same
``TENANT_PAYLOAD_KEY`` filter in **both** multitenant and legacy
modes, but with a backwards-compatible "no payload key → pass
through" branch so legacy-only rows that don't carry the payload
key keep working:

* In multitenant mode: filter is the primary tenant-isolation
  layer (unchanged behaviour).
* In legacy mode: collection-name isolation is the primary layer;
  the new payload-level filter is belt-and-braces against tooling
  drift / migration mistakes that could plant a stray foreign-tenant
  row in a legacy collection.

The new ``BACKEND_CAPABILITIES.supports_legacy_mode`` flag declares
which adapter supports the legacy layout (PGVector ``False``,
Qdrant ``True``) so callers can tell the difference machine-
readably.

Tests
-----
* ``tests/unit_test/vectorstore/test_backend_capabilities.py``
  (new) — pins shape + per-flag values for each adapter. Coordinates
  with cuiwenbo task #87 P1-D3 collection metadata Pydantic
  projection so the static capability matrix stays consistent
  across PRs.
* ``tests/unit_test/vectorstore/test_pgvector_translator.py`` and
  ``test_qdrant_filter_translation.py`` — pin the new Or empty-parts
  guard with frozen-dataclass-bypass coverage.
* ``tests/unit_test/vectorstore/test_qdrant_multitenancy_integration.py``
  — new ``test_retrieve_legacy_mode_filters_stray_foreign_payload``
  exercises the P1-V4 belt-and-braces filter on a real ``:memory:``
  Qdrant client: legacy-mode rows without payload key pass through
  (backward compat), own-tenant payload passes, foreign-tenant
  payload is dropped.

Local: ``uv run pytest tests/unit_test/vectorstore/`` →
**156 passed, 10 skipped, 1 warning**.

Spec / scope alignment
----------------------
* task #61 spec v1 § 2.3 P1-V1 → ensure_collection contract doc ✅
* task #61 spec v1 § 2.3 P1-V2 → BACKEND_CAPABILITIES.supports_atomic_batch_upsert ✅
* task #61 spec v1 § 2.3 P1-V3 → Or empty-parts guard ✅
* task #61 spec v1 § 2.3 P1-V4 → retrieve defense-in-depth + supports_legacy_mode ✅
* Lesson #14 multi-iteration cleanup — legacy mode flagged via
  ``supports_legacy_mode`` so a future PR can drop the mode
  entirely once telemetry confirms zero production usage ✅
* Lesson #17 backend 收敛 contract — capability declaration is the
  backend-side contract that lets callers (FE / API / MCP) read a
  single source of truth instead of forking on backend type ✅

Follow-ups (NOT in this PR)
---------------------------
* task #84 P1-G1+G2 graph store boundary tests — ziang
* task #85 P1-D1 e2e shape matrix — huangzhangshu
* task #86 P1-D2 Helm Nebula first-class — Planetegg
* task #87 P1-D3 collection metadata vector_backend projection —
  cuiwenbo + dongdong (consumes ``BACKEND_CAPABILITIES`` values)
* task #88 P2-S1+S2 batch alias resolution — Bryce after this PR

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…ton PR #1948 BLOCKER)

Weston PR #1948 architecture CR (msg=910cad66 BLOCKER) caught a real
correctness regression in the initial P1-V4 commit: the uniform
"no payload key → pass through" branch leaked stray ``{}`` payload
rows in the **shared multitenant collection** to every tenant on a
``retrieve(ids=...)`` call.

Local Qdrant ``:memory:`` repro (per Weston): a multitenant
connector ``tenant_a`` writes a point with ``payload={}`` directly
to the shared collection, then ``tenant_a.retrieve([id])`` returns
the row. Because ``upsert()`` always stamps the payload key, the
only way a missing-key row reaches the shared collection is tooling
drift / migration drift — exactly the case P1-V4 defense-in-depth
is supposed to catch.

Fix
---
Mode-specific semantics:

* **Multitenant mode** (shared physical collection): STRICT —
  every row MUST carry ``TENANT_PAYLOAD_KEY`` matching the
  connector's tenant id. No "no payload key → pass through"
  branch, because the shared collection means a missing key would
  expose the row to every tenant.
* **Legacy mode** (per-tenant physical collection, unchanged from
  initial commit): PERMISSIVE — a row that doesn't carry the
  payload key still passes through (typical pre-multitenant data
  shape), but a stray foreign-tenant payload gets dropped (catches
  tooling drift / migration mistakes).

Tests
-----
``test_retrieve_multitenant_mode_strict_requires_payload_key`` (new)
— Weston's exact repro: seed shared collection with ``{}`` payload
+ own-tenant payload + foreign-tenant payload, assert only the
own-tenant row passes through. The legacy-mode permissive
counterpart (``test_retrieve_legacy_mode_filters_stray_foreign_payload``)
stays unchanged so a future refactor that unifies them silently
re-opens the leak fails fast.

Local: ``uv run pytest tests/unit_test/vectorstore/`` →
**157 passed, 10 skipped** (one new case).

Sediment trigger
----------------
This is Lesson #12 v9 fifth-application demo same family — Weston
first-principles repro catches the unified branch as silent leak
that I missed when applying the legacy-compat optimization
uniformly. The narrower ``mode-specific`` framing matches the spec
language ("legacy compat for legacy mode only") more precisely.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>